home *** CD-ROM | disk | FTP | other *** search
/ Best Tools for JAVA / Best Tools for JAVA.iso / JAVA_ALL / JDBC / JDBC_011 / JAVA / SQL / STATEMEN.JAV < prev    next >
Encoding:
Text File  |  1996-11-10  |  9.7 KB  |  253 lines
  1. /*
  2.  * Copyright (c) 1996 Sun Microsystems, Inc. All Rights Reserved.
  3.  *
  4.  * Permission to use, copy, modify, and distribute this software
  5.  * and its documentation for NON-COMMERCIAL purposes and without
  6.  * fee is hereby granted provided that this copyright notice
  7.  * appears in all copies. Please refer to the file "LICENSE"
  8.  * for further important copyright and licensing information.
  9.  *
  10.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF
  11.  * THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
  12.  * TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
  13.  * PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR
  14.  * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
  15.  * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.
  16.  * 
  17.  * THIS SOFTWARE IS NOT DESIGNED OR INTENDED FOR USE OR RESALE AS ON-LINE
  18.  * CONTROL EQUIPMENT IN HAZARDOUS ENVIRONMENTS REQUIRING FAIL-SAFE
  19.  * PERFORMANCE, SUCH AS IN THE OPERATION OF NUCLEAR FACILITIES, AIRCRAFT
  20.  * NAVIGATION OR COMMUNICATION SYSTEMS, AIR TRAFFIC CONTROL, DIRECT LIFE
  21.  * SUPPORT MACHINES, OR WEAPONS SYSTEMS, IN WHICH THE FAILURE OF THE
  22.  * SOFTWARE COULD LEAD DIRECTLY TO DEATH, PERSONAL INJURY, OR SEVERE
  23.  * PHYSICAL OR ENVIRONMENTAL DAMAGE ("HIGH RISK ACTIVITIES").  SUN
  24.  * SPECIFICALLY DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY OF FITNESS FOR
  25.  * HIGH RISK ACTIVITIES.
  26.  */
  27.  
  28. package java.sql;
  29.  
  30. /**
  31.  * <P>A Statement object is used for executing a static SQL statement
  32.  * and obtaining the results produced by it. 
  33.  *
  34.  * <P>Only one ResultSet per Statement can be open at any point in
  35.  * time. Therefore, if the reading of one ResultSet is interleaved
  36.  * with the reading of another, each must have been generated by
  37.  * different Statements. All statement execute methods implicitly
  38.  * close a statment's current ResultSet if an open one exists.
  39.  *
  40.  * @see Connection#createStatement
  41.  * @see ResultSet 
  42.  */
  43. public interface Statement {
  44.  
  45.     /**
  46.      * Execute a SQL statement that returns a single ResultSet.
  47.      *
  48.      * @param sql typically this is a static SQL SELECT statement
  49.      * @return a ResultSet that contains the data produced by the
  50.      * query; never null 
  51.      */
  52.     ResultSet executeQuery(String sql) throws SQLException;
  53.  
  54.     /**
  55.      * Execute a SQL INSERT, UPDATE or DELETE statement. In addition,
  56.      * SQL statements that return nothing such as SQL DDL statements
  57.      * can be executed.
  58.      *
  59.      * @param sql a SQL INSERT, UPDATE or DELETE statement or a SQL
  60.      * statement that returns nothing
  61.      * @return either the row count for INSERT, UPDATE or DELETE or 0
  62.      * for SQL statements that return nothing
  63.      */
  64.     int executeUpdate(String sql) throws SQLException;
  65.  
  66.     /**
  67.      * In many cases, it is desirable to immediately release a
  68.      * Statements's database and JDBC resources instead of waiting for
  69.      * this to happen when it is automatically closed; the close
  70.      * method provides this immediate release.
  71.      *
  72.      * <P><B>Note:</B> A Statement is automatically closed when it is
  73.      * garbage collected. When a Statement is closed, its current
  74.      * ResultSet, if one exists, is also closed.  
  75.      */
  76.     void close() throws SQLException;
  77.  
  78.     //----------------------------------------------------------------------
  79.  
  80.     /**
  81.      * The maxFieldSize limit (in bytes) is the maximum amount of data
  82.      * returned for any column value; it only applies to BINARY,
  83.      * VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR
  84.      * columns.  If the limit is exceeded, the excess data is silently
  85.      * discarded.
  86.      *
  87.      * @return the current max column size limit; zero means unlimited 
  88.      */
  89.     int getMaxFieldSize() throws SQLException;
  90.     
  91.     /**
  92.      * The maxFieldSize limit (in bytes) is set to limit the size of
  93.      * data that can be returned for any column value; it only applies
  94.      * to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and
  95.      * LONGVARCHAR fields.  If the limit is exceeded, the excess data
  96.      * is silently discarded. For maximum portability use values
  97.      * greater than 256.
  98.      *
  99.      * @param max the new max column size limit; zero means unlimited 
  100.      */
  101.     void setMaxFieldSize(int max) throws SQLException;
  102.  
  103.     /**
  104.      * The maxRows limit is the maximum number of rows that a
  105.      * ResultSet can contain.  If the limit is exceeded, the excess
  106.      * rows are silently dropped.
  107.      *
  108.      * @return the current max row limit; zero means unlimited
  109.      */
  110.     int getMaxRows() throws SQLException;
  111.  
  112.     /**
  113.      * The maxRows limit is set to limit the number of rows that any
  114.      * ResultSet can contain.  If the limit is exceeded, the excess
  115.      * rows are silently dropped.
  116.      *
  117.      * @param max the new max rows limit; zero means unlimited 
  118.      */
  119.     void setMaxRows(int max) throws SQLException;
  120.  
  121.     /**
  122.      * If escape scanning is on (the default), the driver will do
  123.      * escape substitution before sending the SQL to the database. 
  124.      *
  125.      * @param enable true to enable; false to disable
  126.      */
  127.     void setEscapeProcessing(boolean enable) throws SQLException;
  128.  
  129.     /**
  130.      * The queryTimeout limit is the number of seconds the driver will
  131.      * wait for a Statement to execute. If the limit is exceeded, a
  132.      * SQLException is thrown.
  133.      *
  134.      * @return the current query timeout limit in seconds; zero means unlimited 
  135.      */
  136.     int getQueryTimeout() throws SQLException;
  137.  
  138.     /**
  139.      * The queryTimeout limit is the number of seconds the driver will
  140.      * wait for a Statement to execute. If the limit is exceeded, a
  141.      * SQLException is thrown.
  142.      *
  143.      * @param seconds the new query timeout limit in seconds; zero means unlimited 
  144.      */
  145.     void setQueryTimeout(int seconds) throws SQLException;
  146.  
  147.     /**
  148.      * Cancel can be used by one thread to cancel a statement that
  149.      * is being executed by another thread.
  150.      */
  151.     void cancel() throws SQLException;
  152.  
  153.     /**
  154.      * The first warning reported by calls on this Statement is
  155.      * returned.  A Statment's execute methods clear its SQLWarning
  156.      * chain. Subsequent Statement warnings will be chained to this
  157.      * SQLWarning.
  158.      *
  159.      * <p>The warning chain is automatically cleared each time
  160.      * a statement is (re)executed.
  161.      *
  162.      * <P><B>Note:</B> If you are processing a ResultSet then any
  163.      * warnings associated with ResultSet reads will be chained on the
  164.      * ResultSet object.
  165.      *
  166.      * @return the first SQLWarning or null 
  167.      */
  168.     SQLWarning getWarnings() throws SQLException;
  169.  
  170.     /**
  171.      * After this call, getWarnings returns null until a new warning is
  172.      * reported for this Statement.  
  173.      */
  174.     void clearWarnings() throws SQLException;
  175.  
  176.     /**
  177.      * setCursorname defines the SQL cursor name that will be used by
  178.      * subsequent Statement execute methods. This name can then be
  179.      * used in SQL positioned update/delete statements to identify the
  180.      * current row in the ResultSet generated by this statement.  If
  181.      * the database doesn't support positioned update/delete, this
  182.      * method is a noop.
  183.      *
  184.      * <P><B>Note:</B> By definition, positioned update/delete
  185.      * execution must be done by a different Statement than the one
  186.      * which generated the ResultSet being used for positioning. Also,
  187.      * cursor names must be unique within a Connection.
  188.      *
  189.      * @param name the new cursor name.  
  190.      */
  191.     void setCursorName(String name) throws SQLException;
  192.     
  193.     //----------------------- Multiple Results --------------------------
  194.  
  195.     /**
  196.      * Execute a SQL statement that may return multiple results.
  197.      * Under some (uncommon) situations a single SQL statement may return
  198.      * multiple result sets and/or update counts.  Normally you can ignore
  199.      * this, unless you're executing a stored procedure that you know may
  200.      * return multiple results, or unless you're dynamically executing an
  201.      * unknown SQL string.  The "execute", "getMoreResults", "getResultSet"
  202.      * and "getUpdateCount" methods let you navigate through multiple results.
  203.      *
  204.      * The "execute" method executes a SQL statement and indicates the
  205.      * form of the first result.  You can then use getResultSet or
  206.      * getUpdateCount to retrieve the result, and getMoreResults to
  207.      * move to any subsequent result(s).
  208.      *
  209.      * @param sql any SQL statement
  210.      * @return true if the next result is a ResultSet; false if it is
  211.      * an update count or there are no more results
  212.      * @see #getResultSet
  213.      * @see #getUpdateCount
  214.      * @see #getMoreResults 
  215.      */
  216.     boolean execute(String sql) throws SQLException;
  217.     
  218.     /**
  219.      *  getResultSet returns the current result as a ResultSet.  It
  220.      *  should only be called once per result.
  221.      *
  222.      * @return the current result as a ResultSet; null if the result
  223.      * is an update count or there are no more results
  224.      * @see #execute 
  225.      */
  226.     ResultSet getResultSet() throws SQLException; 
  227.  
  228.     /**
  229.      *  getUpdateCount returns the current result as an update count;
  230.      *  if the result is a ResultSet or there are no more results, -1
  231.      *  is returned.  It should only be called once per result.
  232.      * 
  233.      * @return the current result as an update count; -1 if it is a
  234.      * ResultSet or there are no more results
  235.      * @see #execute 
  236.      */
  237.     int getUpdateCount() throws SQLException; 
  238.  
  239.     /**
  240.      * getMoreResults moves to a Statement's next result.  It returns true if 
  241.      * this result is a ResultSet.  getMoreResults also implicitly
  242.      * closes any current ResultSet obtained with getResultSet.
  243.      *
  244.      * There are no more results when (!getMoreResults() &&
  245.      * (getUpdateCount() == -1)
  246.      *
  247.      * @return true if the next result is a ResultSet; false if it is
  248.      * an update count or there are no more results
  249.      * @see #execute 
  250.      */
  251.     boolean getMoreResults() throws SQLException; 
  252. }    
  253.